<!--break-->

<h3>Prequels</h3>
<i>"When you think of things, you find sometimes that a Thing which seemed very Thingish inside you is quite different when it gets out into the open and has other people looking at it." Winnie the Pooh</i>

<img alt="" src="http://weblogs.java.net/blog/evanx/archive/eeyore_side_crop.jpg" width="134" height="151" align=left hspace=16 vspace=4 />

<!--img alt="eeyore" src="http://weblogs.java.net/blog/evanx/archive/eeyore_sit_crop_150.jpg" width="150" height="174"     
align=left hspace=16 border=0 /-->

In <a href="http://weblogs.java.net/blog/evanx/archive/2006/05/bean_curd_chapt.html">Turn Tables</a> we introduced an "explicit properties" approach, where the property descriptors are absorbed into our <tt>TableColumn</tt> objects, which are declared in our custom <tt>TableModel</tt>.

In <a href="http://weblogs.java.net/blog/evanx/archive/2006/06/bean_curd_2_the.html">The SQL}</a> we apply the <i>explicit properties</i> approach to object-relational mapping (ORM), to support "native queries," for loading <i>entity beans.</i>

Another (technical) Swing article I wrote in addition to "Swing turntables" is <a href="http://javakenai-dev.cognisync.net/blog/2006/05/30/swing-and-roundabouts-1-event-dts">Event DTs</a>

As always, this is a noisy article. The noisy bits are italicised, just so you know.

<h3>Introduction</h3>
<i>"I didn't look around because if you look around and see a Very Fierce Heffalump looking down at you, sometimes you forget what you were going to say. It's hard to be brave, when you're only a Very Small Animal." Piglet</i>

The application archetype I'm mostly interested in is database front-ends. You could call these CURD applications, for Create, Update, Retrieve and Delete. Some other people call them CRUD applications, and that's OK ;)

So we use an ORM to load our "entity beans" from the database. We view and edit 
these in our Swing application. Finally we'll save them back to the database (using our ORM's entity manager). Or we create new entity beans in Swing, and save those to the database. Or we delete entity beans from the database. <i>It's all the same, urm, crud.</i>

<tt>JTable</tt> is great for browsing the database. But in this article we look at viewing and editing an entity object using a Swing "form." This is a <tt>JPanel</tt> with components on it like <tt>JTextField</tt>, <tt>JComboBox</tt>, and <tt>JCheckbox</tt>.

Colleagues and I have (re)implemented a similar approach for a few projects. Most recently it is implemented in <a href="">java.net/projects/greenscreen}, which is used by <a href="">java.net/projects/aptframework</a>. This paper presents a refined design compared to <i>greenscreen,</i> in particular with respect to validation, which will make it's way into <i>greenscreen</i> in coming weeks (or months). 

It is a simple Swing GUI data binding framework, e.g. one can implement 80% of it from scratch in a few days. <i>Because 80% of <u>greenscreen</u> took me three days... and nights. I forgot about the nights, actually. The remaining 20% might take a little while longer ;) It has a few downsides I'm sure, but it works for us. I'm sure it breaks a few laws of OO, gravity and what-not. So at least it acheives that objective! ;)</i>
</i>

<img alt="tigger-hacking" src="http://weblogs.java.net/blog/evanx/archive/tigger-hacking_out_175.jpg" width="175" height="164" align=right hspace=16 vspace=8 />

<h3>Entity bean</h3>
<i>"And the Small and Sorry Rabbit rushed through the mist at the noise, and it suddenly turned into Tigger; a Friendly Tigger, a Grand Tigger, a Large and Helpful Tigger, a Tigger who bounced, if he bounced at all, in just the beautiful way a Tigger ought to bounce." A. A. Milne</i>

<i>My friend Tigger wrote this bouncy Swing app to keep a handy list of our friends in the forest. Like Roo, Piglet, Eeyore, Rabbit and Owl. Tigger asked me to write this article for him. Because he has a rule about writing documentation. That rule is that he gets me to do it for him.</i>

Let's start with our entity bean. <i>That is to say, let's climb up the tree, and then look down, rather than the other way around.</i>

<pre>
/**
 * This is a for my friends.
 * @author Tigger
 */
public class FriendEntityBean {
   protected String friendName; // e.g. "Pooh"
   protected FriendType friendType; // an enum, e.g. POOH_BEAR
   protected ForestFood favouriteFood; // e.g. a reference to honey in Pooh's case
   protected Date birthday;
   protected int age; // when the system is first deployed

   ... // getters and setters  
}
</pre>

<h3>Presentation Model bean</h3>
<i>"It's a funny thing, how everything looks the same in a mist." Piglet</i>

In a simplistic CURD application, the bean we view and edit in our form might be our raw entity bean. <i>But to get flexibility, Tigger likes to wrap his entity beans into more chewy beans, as follows.</i>

<pre>
public class FriendFormBean {
   protected FriendEntityBean entityBean;
   protected FriendEntityBean originalEntityBean; // for isChanged()
   protected boolean created = false;
   protected boolean deleted = false;
   
   public FriendFormBean() {
      // we are creating a new entity to capture
      entityBean = new FriendEntityBean();      
      originalEntityBean = entityBean.clone();
      created = true;
   }

   public FriendFormBean(FriendEntityBean entityBean) {
      // we are editing an entity we read from the database
      this.entityBean = entityBean;
      originalEntityBean = entityBean.clone();
   }

   public boolean isChanged() {
      return entityBean.compareTo(originalEntityBean) != 0;
   }

   public String getValidationMessage() {
      if (getFriendName() == null) return "Friend's name is null";
      if (getFriendName().trim().length() == 0) return "Friend's name is empty";
      ...
      return null;
   }
   
   public String getFriendName() {
      return entityBean.getFriendName();
   }

   @IntegerRangeValidationAnnotation(minimumValue = 0, maximumValue = 9)
   public void setAge(int age) {
      if (age < 0 || age > 9) {
         throw new GValidationException(
            "They're a funny thing, accidents.\n" + 
            "You never have them til you're having them.\n" +
            "Like now. - Piglet");
      }
      entityBean.setAge(age);
   }

   @NotNullValidationAnnotation()
   public void setFavouriteFood(ForestFood food) {
      entityBean.setFavouriteFood(food);   
   }
   
   @DateNotInFutureValidationAnnotation()
   public void setBirthday(Date birthday) {
      entityBean.setBirthday(birthday);   
   }
   
   ... // other delegating getters and setters, isCreated(), isDeleted()
}
</pre>

The above bean is a "model bean" representing the data to be displayed in our form. Since this is mostly data in the entity bean, we delegate to the entity bean a lot.

<img alt="heffalump" src="http://weblogs.java.net/blog/evanx/archive/heffalump_125.jpg" width="125" height="104" align=left hspace=16 />    

<i>It isn't really a bean, it's just a POJO. As Owl will tell you. But Tigger likes to call everything a bean.</i>
    
We show some simple validation mechanisms above. One, we can throw a <tt>GValidationException</tt> in our mutators, e.g. <tt>setAge()</tt>. Two, we might have a method like <tt>getValidationMessage()</tt> to check that our data is OK e.g. before we save it to the database. Three, we might put annotations on our mutators, e.g. <tt>IntegerRangeValidationAnnotation</tt>. And finally... <i>Oh, that's still to come, in the next section.</i> 
 
<h3>Formative Panel</h3>
<i>"This writing business. Pencils and what-not. Overrated if you ask me. Silly stuff. Nothing in it." Eeyore</i>

<i>Tigger implements a "form" as a <tt>JPanel</tt> with a number of "fields" on it. With a whole honey pot of annotations. And ever since Tigger heard of this MVC thing, he tries to label things along those lines. So our form is called a "view." Of the "model bean" we introduced above.</i>

<pre>
public FriendFormView extends JPanel {

   GFormHelper<FriendFormBean> helper = new GFormHelper(this, FriendFormBean.class);

   @PropertyAnnotation(label = "Name", mnemonic = 'N', displayWidth = 250)
   @LayoutAnnotation(anchor = NORTHWEST)
   @StringValidatorAnnotation(minimumLength = 1)
   @TextFieldAnnotation(maximumLength = 20) // custom annotations for text fields
   JTextField friendName = helper.createTextField();
   
   @PropertyAnnotation(label = "Type of Animal", displayWidth = 200)
   @LayoutAnnotation(fill = HORIZONTAL)
   @ComboBoxAnnotation(selectNoneLabel = "Not specified")
   JComboBox friendType = helper.createComboBox();

   @PropertyAnnotation(label = "Favourite food", displayWidth = 250)
   @LayoutAnnotation()
   @TextFieldAnnotation() // custom annotations for text fields
   JTextField favouriteFood = helper.createTextField(); // lookup field
   
   @PropertyAnnotation(label = "To be deleted")
   @LayoutAnnotation(flow = NEW_LINE, spacer = BOTH)
   @CheckBoxAnnotation(selected = false)
   JCheckBox deleted = helper.createCheckBox();

   ...
   
   public FriendFormView() {   
      super();
      helper.configure();
   }
   
}
</pre>

As in <a href="http://weblogs.java.net/blog/evanx/archive/2006/05/bean_curd_chapt.html">Swing Turntables</a>, we let our components get created in the order they are declared, and then finally invoke <tt>configure()</tt> in the constructor. This reflects on the declared fields, so that they can configure themselves using their own <tt>Field</tt>, e.g. they extract their own field name to be used as the implicit property name for beans binding. And they also extract annotations, which we can use to configure the component, including annotations for validation and layout, as above.

<img alt="" src="http://weblogs.java.net/blog/evanx/archive/tigger_beer_175.jpg" width="175" height="162"  align=left hspace=16 />
In the example above, we include the default label and display width for each field in the <tt>PropertyAnnotation</tt>. But we should translate/customise these in a resource bundle. In the case of the display width, we might save and load this using the Preferences API. For example, our fields might listen for a keystroke to increase and decrease their size.

We might also include layout settings in our <tt>LayoutAnnotation</tt>, e.g. <tt>gridx</tt>, <tt>gridy</tt>. We try to use <tt>GridBagLayout</tt> exclusively. But by default we use <tt>FlowLayout</tt> to flow fields horizontally in a subpanel, and then <tt>GridBagLayout</tt> to stack subpanels, and throw in a "spacer panel" or two, according to the annotations, e.g. <tt>fill</tt>, <tt>anchor</tt>, <tt>flow</tt>, and <tt>spacer</tt>. We have introduced <tt>flow</tt> and <tt>spacer</tt>, to compliment <tt>GridBagLayout</tt>'s <tt>fill</tt> and <tt>anchor</tt>, you see.

<i>In general, when writing business apps, enterprise apps, database-front-ends, and such like, we are more interested in keeping it bouncy than anything else. Our "screens" (and reports and what-not), must be quick to implement, and easy for developers to extend and change. So that their weekends are free as in beer. Tiggers are agile and fuzzy creatures, and like to write software that is agile and fuzzy too.</i>

<i>A GUI designer tool makes it easy to build beautiful GUIs, without having to be a Swing expert. Roo prefers GUI designers, and Tigger prefers IDE-agnostic frameworks. Who is right? Owl says they both are right. And that makes them both happy.</i>

<h3>Swing honey pot</h3>
<i>"It's always useful to know where a friend-or-relation is, whether you want him or whether you don't." Roo</i>

There a few places where we can put our "framework" code. We could have a superclass (which extends <tt>JPanel</tt>). Or we could put it into a friendly helper class, which we delegate to. This is what Tigger does. That is to say, he prefers composition and delegation to inheritance. In this case, it is possible to have methods in the superclass, that delegate to the helper. <i>And in other superclasses too, although none come to mind immediately.</i>

<pre>
public class GFormHelper<Bean> implements ActionListener, FocusListener {
   protected JPanel viewObject;
   protected Bean bean;
   protected GBeanInfo beanInfo;
   protected List<GLayoutComponent> layoutComponentList = new ArrayList();
   protected List<GFieldComponent> fieldComponentList = new ArrayList();
   protected boolean ignoreEvents = false;
   protected Object controllerObject = null;
   
   public GFormHelper(JPanel viewObject, Class beanClass) {
      this.viewObject = viewObject;   
      viewObject.setLayout(new GridBagLayout());
      this.beanInfo = new GBeanInfo(beanClass);
   }
   
   public JTextField createTextField() {
      GTextField textField = new GTextField(this);
      configure(textField);
      return textField;
   }

   public void configure(GTextField textField) {
      layoutComponentList.add(textField); // for adding to the panel later in configure()
      fieldComponentList.add(textField); // for bean binding in getModelBean() and setModelBean()
      ... // other custom configuration
   }
      
   public void configure() {
      for (Field field : viewObject.getClass().getFields()) {
         field.setAccessible(true);
         Object object = field.get(viewObject);
         if (object instanceof GFieldComponent) {
            GFieldComponent component = (GFieldComponent) object;
            component.configure(field, beanInfo); // for field name, and annotations
         }
      }
      for (GLayoutComponent component : layoutComponentList) {
         viewObject.add(component, component.getLayoutConstraints());
      }
   }
   
   public void setModelBean(Bean bean) { // update fields from bean
      ignoreEvents = true;
      try {
         for (GFieldComponent component : fieldComponentList) {
            component.setModelBean(bean);
         }
      } finally {
         ignoreEvents = false;
      }   
   }

   public Bean getModelBean() { // update bean from field values
      for (GFieldComponent component : fieldComponentList) {
         component.getModelBean(bean);
      }
      return bean;
   }
   
   public void actionPerformed(ActionEvent event, GFieldComponent fieldComponent) {
      eventLogger.entering(event, ignoreEvents);
      if (!ignoreEvents) {
         ignoreEvents = true;
         try {
            fieldComponent.getModelBean(bean); // update the bean
            if (controllerObject instanceof ActionListener) {
               ActionListener actionListener = (ActionListener) controllerObject;
               actionListener.actionPerformed(event);
            }
            ... // invoke controllerObject.fieldChanged()
         } catch (GParseException pe) {
            showExceptionDialog(pe);
            fieldComponent.requestFocusInWindow();
         } catch (GValidationException ve) {
            showExceptionDialog(ve);
            fieldComponent.requestFocusInWindow();
         } catch (Exception e) {
            showExceptionDialog(e);
         } finally {
            ignoreEvents = false;
         }
      }   
   }
   
   ... // lots of other methods, e.g. createComboBox() et al
}
</pre>

We use a trick for "automatic" event listener registration, where if our controller is an ActionListener, then we forward it action events from its components. Similarly with other types of events, e.g. FocusListener. 

<img alt="eeyore" src="http://weblogs.java.net/blog/evanx/archive/eeyore_beer_crop.jpg" width="180" height="165" align=right hspace=8 />
Note that we ignore action events when we are reading from the bean into the form's fields in <tt>setModelBean()</tt>. In this case, the user is not editing a field, but the developer refreshing the fields from the current values of the bean properties.

When an <tt>ActionEvent</tt> occurs on the field, we invoke the overloaded <tt>actionPerformed()</tt> above, with a reference to the relevant field as the second argument. We then update the bean with the new value from the field. At this point, the bean's mutator might throw a <tt>GValidationException</tt>.

We make sure we catch exceptions that are thrown by event handlers, and display those to the user. Exceptions might be tiny unexpected errors, like null pointers, caused by the developer having too much to do, too soon. Or they might be expected exceptions, like validation exceptions, caused by the user making a big Heffalump mistake like typing the wrong thing at the wrong time, which is totally not allowed of course. 

If the user enters a field and we throw a validation exception, we should keep focus on that field, so that the user can get his act together e.g. enter a valid value. In the case of a <tt>JFormattedTextField</tt>, we can use an <tt>InputVerifier</tt> to nail this too. 

<h3>One field component</h3>
<i>"The most wonderful thing about Tiggers is, I'm the only one!" Tigger</i>

We extend the Swing components <tt>JTextField</tt>, <tt>JFormattedTextField</tt>, <tt>JComboBox</tt>, <tt>JPasswordField</tt>, <tt>JCheckBox</tt> etcetera, in a minimal way, in order to implement <tt>GFieldComponent</tt> so that they all start looking like nails, to be hammered into our form.

<pre>
public interface GFieldComponent<Value> extends GLayoutComponent {
   public void configure(Field field, GBeanInfo beanInfo);
   public void setFieldValue(Value value);
   public Value getFieldValue();
   public String format(Value value);
   public Value parse(String string); // throws GParseException, GValidationException
   ... // other methods, e.g. requestFocusInWindow(), used by GFormHelper
}
</pre>    

<h3>Laying it out</h3>
<i>"Always watch where you are going. Otherwise, you may step on a piece of the Forest that was left out by mistake."</i>
    
Components that we are gonna add to the form panel, need to implement the <tt>GLayoutComponent</tt> interface, i.e. our fields, but also buttons and what-not.

<pre>
public interface GLayoutComponent {
   public GLayoutConstraints getLayoutConstraints();
}
</pre>

We extend <tt>GridBagConstraints</tt> to make it chocolaty (see http://java.net/projects/gridbaglady).

<pre>
public class GLayoutConstraints extends GridBagConstraints {
   protected int flow; // to mix in flowing sub-panels, i.e. using FlowLayout
   protected int spacer; // for adding spacer panels
      // i.e. JPanel with gbc.fill set to this spacer value
   ...
   
   public GLayoutConstraints() {
   }

   public GLayoutConstraints(int gridx, int gridy) {
      super(gridx, gridy, 1, 1, 0., 0., NORTHWEST, NONE, new Insets(0, 0, 0, 0), 0, 0);
   }
   
   public GLayoutConstraints horizontal() {
      super.fill = HORIZONTAL;
      return this;
   }
   
   ...
}
</pre>

But for the purposes of keeping this article bear-shaped, let's just pretend we use the vanilla <tt>GridBagConstraints</tt>.

<img alt="eeyore" src="http://weblogs.java.net/blog/evanx/archive/eeyore_rabbit_crop.jpg" width="163" height="136" align=left hspace=16 vspace=4 />

<h3>Text field example</h3>
<i>"It's a funny thing about Tiggers," whispered Tigger to Roo, "how Tiggers never get lost." "Why don't they, Tigger?" "They just don't," explained Tigger. "That's how it is."</i>

Our field components implement the <tt>GFieldComponent</tt> interface, and delegate to a helper e.g. <tt>GTextFieldHelper</tt>. This helper is a thin customised extension of <tt>GFieldComponentHelper</tt> which handles the common functionality e.g. beans binding, for which it uses <tt>GProperty</tt>, as we will see later.

<i>It sounds convoluted when put into words, so maybe Tigger lost the plot here. Which can happen when Winnie the Pooh comes over for a 11 o' clock smackerel of something. He disrupts Tigger's train of thought, you see.</i>
    
<pre>
public class GTextField<Value> extends JTextField implements GFieldComponent<Value> {

   GTextFieldHelper<Value> helper = new GTextFieldHelper(this);
 
   public GTextField(GFormHelper formHelper) {
      super();
      helper.setFormHelper(formHelper);
   }
   
   public void configure(Field field, GBeanInfo beanInfo) {
      helper.configure(field, beanInfo);
   }   

   public GLayoutConstraints getLayoutConstraints() {
      return helper.getLayoutConstraints();
   }
   
   public void setFieldValue(Value value) {
      super.setText(format(value));
   }

   public Value getFieldValue() {
      return parse(super.getText());
   }

   public String format(Value value) { // in case we wanna override
      return helper.format(value);
   }

   public Value parse(String string) { // in case we wanna override
      return helper.parse(string);
   }   
   
   ... // other methods of GFieldComponent interface, which we delegate out to our helper
}      
</pre>

<img alt="eeyore" src="http://weblogs.java.net/blog/evanx/archive/eeyore_slouch_100.jpg" width="100" height="147" align=right hspace=16 vspace=8 />

In the case of <tt>GCheckBox</tt>, it's <tt>getFieldValue()</tt> will invoke <tt>isSelected()</tt> and return a <tt>Boolean</tt>. 
    
<tt>GComboBox</tt>'s <tt>getFieldValue()</tt> delegates to its <tt>GComboBoxModel</tt> to lookup the object value associated with it's <tt>getSelected()</tt> label, as we will see later.

<h3>Field component helpers</h3>
<i>'What?' said Piglet, with a jump. And then to show that he hadn't been startled, he jumped up and down once or twice more in an exercising sort of way.</i>

Our <tt>GTextFieldHelper</tt> keeps a reference to its peer <tt>GTextField</tt>, and performs any functionality specific to <tt>JTextField</tt>. But otherwise, the <tt>GFieldComponentHelper</tt> superclass is the main Heffalump.

<pre>
public class GTextFieldHelper<Value> extends GFieldComponentHelper<Value> {
   GTextField<Value> textField;
   
   public GTextFieldHelper(GTextField<Value> textField) {
      super(textField);
      this.textField = textField;
   }
   
   public void configure(Field field, GBeanInfo beanInfo) {      
      super.configure(field, beanInfo); // PropertyAnnotation, 
          // LayoutAnnotation, and validation annotations
      ... // process TextFieldAnnotation
   }      
}   
</pre>

The <tt>configure()</tt> methods extract the configuration annotations from the <tt>Field</tt>.

<tt>GComboBoxHelper</tt> and <tt>GCheckBoxHelper</tt> are very much like the above. The Heffalump superclass is implemented as follows.

<pre>
/**
 * Superclass for GTextFieldHelper, GComboBoxHelper, GCheckBoxHelper, et al.
 * @author Tigger
 */    
public class GFieldComponentHelper<Value> implements ActionListener, FocusListener {
   GFormHelper formHelper;
   GFieldComponent<Value> fieldComponent;
   GLayoutConstraints layoutConstraints;
   GProperty<Value> property;
   
   /**
    * Boa Constructor.
    */    
   public GFieldComponentHelper(GFieldComponent<Value> fieldComponent) {
      this.fieldComponent = fieldComponent;
   }

   /**
    * Get the GProperty from beanInfo, configured using PropertyAnnotation et al
    * Note, we should also invoke setFormHelper() to finally configure this baby.
    * @see GBeanInfo#createProperty(Field)
    */
   public void configure(Field field, GBeanInfo beanInfo) {      
      property = beanInfo.createProperty(field);
      fieldComponent.addActionListener(this); // forwards events to GFormHelper
   }   
   
   /**
    * Forward event to formHelper with reference to source field component.
    * @see GFormHelper#actionPerformed(ActionEvent)
    */
   public void actionPerformed(ActionEvent event) {
      formHelper.actionPerformed(event, fieldComponent); 
   }
   
   /**
    * Format value to viewable string representation, by delegation to GProperty.
    * @see GProperty#format(Value)
    */
   public String format(Value value) {
      return property.format(value);
   }

   /**
    * Convert and validate string, by delegation to GProperty.
    * @see GProperty#parse(String)
    */
   public Value parse(String string) {
      return property.parse(string);
   }   

   /**
    * Push value into field component from bean.
    * @see GProperty#getValue(Bean)
    */
   public void setModelBean(Object bean) { 
      fieldComponent.setFieldValue(property.getValue(bean));
   }

   /**
    * Pull value from field component into bean.
    * @see GProperty#setValue(Bean, Value)
    */
   public void getModelBean(Object bean) { 
      property.setValue(bean, fieldComponent.getFieldValue());
   }
      
   ... // other methods
}      
</pre>
    
We use the <tt>GProperty</tt> property descriptor wrapper, to read and write that property's values to and from our bean, e.g. an instance of <tt>FriendFormBean</tt>. And also to format, parse and validate property values to and from their string representations. <i>Heh heh... Hm... Eh?</i>

<img alt="eeyore" src="http://weblogs.java.net/blog/evanx/archive/eeyore_sit_side_crop3.jpg" width="115" height="95" align=left hspace=16 vspace=8 border=0 />

<h3>Combo box</h3>
<i>"I used to believe in forever, but forever is too good to be true." Winnie the Pooh</i>

We implement <tt>GComboBox</tt> as follows. <i>I don't understand this, so I'm just gonna present it. Any questions, post them. Then my people will get hold of Tigger's people and get back to your people.</i>

<pre>
public class GComboBox<Value> extends JComboBox implements GFieldComponent<Value> {

   GComboBoxHelper<Value> helper = new GComboBoxHelper(this);
 
   public GComboBox() {
      super();
   }
   
   public void configure(Field field, GBeanInfo beanInfo) {
      helper.configure(field, beanInfo);
   }   
   
   public void setFieldValue(Value value) {
      super.setSelected(format(value));
   }

   public Value getFieldValue() {
      return parse(super.getSelected().toString());
   }

   public String format(Value value) {
      return helper.format(value);
   }

   public Value parse(String string) {
      return helper.parse(string);
   }   
   
   ... // other methods of GFieldComponent interface, which we delegate out to the helper
}      
</pre>

<tt>GComboBoxHelper</tt> in turn delegates the <tt>format()</tt> and <tt>parse()</tt> to <tt>GComboBoxModel</tt>. <i>I asked Tigger why so much delegation, from the component to the helper, to the model. He said, "To make it more bouncy, of course!"</i> 

<h3>Combo box model</h3>
<i>"I don't see much sense in that," said Piglet. "No," said Pooh humbly, "there isn't. But there was going to be when I began it. It's just that something happened to it along the way."</i>

We implement a "generic" combo box model to be reusable by all combo boxes. 
    
<pre>
public class GComboBoxModel<Value> extends DefaultComboBoxModel {
   GComboBoxHelper<Value> helper;
   List<Value> valueList = new ArrayList();
   Map<String, Value> valueMap = new HashMap();
   String selectNoneLabel = "Select...";
   String selectAllLabel = "The whole honey pot";
   
   ... 
   public void add(String label, Value value) {
      valueMap.put(label, value);
      valueList.add(value);
   }

   public void add(Value value) {
      add(format(value), value);
   }
   
   public void addAll(Value ... values) {
      for (Value value : values) {
         add(value);
      }
   }

   public void addAll(List<Value> valueList) {
      for (Value value : valueList) {
         add(value);
      }
   }
   
   public void addSelectNone(String label) {
      add(label, null);
      selectNoneLabel = label;
   }

   public void addSelectAll(String label) {
      add(label, null);
      selectAllLabel = label;
   }

   public String format(Value value) {
      return helper.comboBox.format(value);
   }

   public Value parse(String label) {
      return valueMap.get(label);
   }
     
   public Object getElementAt(int index) { // implementing ComboBoxModel
      return format(valueList.get(index));
   }

   public int getSize(int index) { // implementing ComboBoxModel
      return valueList.size;
   }
   
   public boolean isSelectNone() {
      return getSelected().equals(selectNoneLabel);
   }

   public boolean isSelectAll() {
      return getSelected().equals(selectAllLabel);
   }
   
}
</pre>

<!--img alt="eeyore" src="http://weblogs.java.net/blog/evanx/archive/eeyore_lift_crop.jpg" width="119" height="186" align=right  hspace=16 /-->

A <tt>null</tt> value might correspond to a selection of "All" or "None" or both. So we offer methods like <tt>isSelectAll()</tt> so we can check, i.e. when the value is null, and we have "All" and "None" as available selections, when which is it?

<i>There is Another Big Issue. Usually we want to support auto-completion for combo boxes. But we gonna dodge that issue for now.</i>

<h3>Filling the combo box</h3>
<i>"Company means Food... and Listening-to-Me-Humming and such like." Winnie the Pooh</i>

We might populate a combo box model from an <tt>enum type</tt> as follows.    

<pre>
   public void addFriendTypes(GComboBox comboBox) {
      for (FriendType friendType : FriendType.values()) {
         comboBox.getComboBoxModel().add(friendType.toString(), friendType);
      }
   }
</pre>

Another example would be populating from a database table, e.g. via a DAO method e.g. <tt>foodComboBoxModel.addAll(entityManager.food.getEntityList())</tt>.

<i>For very large tables, i.e. "high volume" combo boxen, we gotta treat those as A Special Case. With auto-completion and reactive fetching and populating of the combo box. And multi-column combo boxes and database lookup-popups. Here's a suggestion, let's seriously forget about all that for now. And leave it for "Swing and Roundabouts: My big fat geeky combo box".</i>

<i>Hope they bought that? Phew, that was a close one. Tigger better work out how to do all that at some stage!</i>

<h3>Bean wiring</h3>
<i>"Poetry and Hums aren't things which you get, they're things which get you. And all you can do is go where they can find you." Winnie the Pooh</i>

We should have introduced the <tt>GBeanInfo</tt> and <tt>GProperty</tt> wrappers sooner. Here they are, later.

<pre>
public class GBeanInfo<Bean> {
   protected BeanInfo beanInfo;
   protected Map<String, GProperty> propertyMap;
      
   public GBeanInfo(Class beanClass) {
      this.beanInfo = Introspector.getBeanInfo(beanClass);
      for (PropertyDescriptor propertyDescriptor : beanInfo.getPropertyDescriptors()) {
         GProperty property = new GProperty(this, propertyDescriptor)
         propertyMap.put(propertyDescriptor.getPropertyName(), property);
      }
   }
   
   public GProperty getProperty(String propertyName) {
      return propertyMap.get(propertyName);
   }
   
   public GProperty createProperty(Field field) {
      return propertyMap.get(field.getName()).configure(field);
   }

}
</pre>

We use <tt>GProperty</tt> to read and write to the bean, basically.

<pre>
public class GProperty<Value> {
   protected GBeanInfo beanInfo;
   protected PropertyDescriptor propertyDescriptor;
   protected String label;
   protected GPropertyType propertyType; 
   protected Integer displayWidth;
   protected String format;
   protected List<GValidator> validatorList = new ArrayList();
   protected GFormatter formatter = GContext.getFormatter();
   ...
   
   public GProperty(GBeanInfo beanInfo, PropertyDescriptor propertyDescriptor) {
      this.beanInfo = beanInfo;
      this.propertyDescriptor = propertyDescriptor;
   }

   public GProperty configure(Field field) {
      // extract PropertyAnnotation, to set label, displayWidth, propertyType et al
      // extract validation annotations, to construct validatorList
      ...
      return this;
   }
   
   public Value getValue(Object bean) {
      return (Value) propertyDescriptor.getReadMethod().invoke(bean);
   }
   
   public void setValue(Object bean, Value value) {
      propertyDescriptor.getWriteMethod().invoke(bean, value);
   }   
   
   public String format(Value value) { // delegate to GFormatter
      return formatter.format(value, this);
   }

   public Value parse(String string) { // throws GParseException 
      return validate(formatter.parse(string, this));
   }

   public Value validate(Value value)  { // throws GValidationException  
      for (GPropertyValidator validator : validatorList) {
         validator.validate(value);
      }
      return value;
   }

   ...
}      
</pre>

We store meta-data extracted from annotations in <tt>GProperty</tt>, required to perform conversion and validation. So let's introduce <tt>GValidator</tt> and <tt>GFormatter</tt> implementations below, to see what we're getting.

<!--img alt="Pooh" src="http://weblogs.java.net/blog/evanx/archive/Pooh_100.jpg" width="100" height="124" align=left hspace=16 /-->

<h3>Validation annotation station</h3>
<i>Pooh looked at his two paws. He knew that one of them was the right, and he knew that when you had decided which one of them was the right, then the other was the left, but he never could remember how to begin.</i>

Our list of <tt>GValidator</tt>'s in <tt>GProperty</tt> is constructed from validation annotations, e.g. <tt>StringValidatorAnnotation</tt>, <tt>IntegerRangeValidatorAnnotation</tt>, <tt>DateRangeValidatorAnnotation</tt>, and any number of other validation annotations we wish to introduce. 

Let's consider the following example.

<pre>
public class GStringValidator extends GValidator<String> {   
   protected Integer minimumLength;
   protected Integer maximumLength;
   protected boolean nullable = false;
   protected boolean empty = false;
   ...
   public void validate(String value) {
      if (value == null) {
         if (!nullable) {
            throw new GValidationException(this, "is null");
         }
         return;
      }         
      if (!empty && value.trim().length() == 0) {
         throw new GValidationException(this, "is empty");
      }
      if (minimumLength != null && value.length() < minimumLength) {
         throw new GValidationException(this, "is shorter than " + minimumLength);
      }
      ...
   }
   
   public void configure(Field field) {
      ... // extract StringValidatorAnnotation to set minimumLength et al
   }         
}
</pre>

Our <tt>GValidator</tt> superclass keeps a reference to its <tt>GProperty</tt>, so that our validation exception messages can report the <tt>label</tt> of the invalid property to the user, e.g. "Friend's name is null". 

We might create an <tt>InputVerifier</tt> for a <tt>JFormattedTextField</tt> as follows.

<pre>
public class GPropertyVerifier extends InputVerifier {
   GProperty property;
   
   public GPropertyVerifier(GProperty property) {
      this.property = property;
   }
   
   public boolean verify(JComponent component) {
      if (component instanceof JFormattedTextField) {
         JFormattedTextField textField = (JFormattedTextField) component;
         String text = textField.getText();
         try {
            property.parse(text);
         } catch (Exception e) {
            return false;
         }
      }
      return true;
   }
   
   public boolean shouldYieldFocus(JComponent component) {
      return verify(component);
   }
}                
</pre>
   
<h3>Annotation aches and panes</h3>
<i>"Don't underestimate the value of Doing Nothing, of just going along, listening to all the things you can't hear, and not bothering." Roo</i>

<img alt="eeyoreg" src="http://weblogs.java.net/blog/evanx/archive/eeyore_fallen_small.jpg" width="90" height="91" align=left hspace=8 />
Unfortunately annotations do not support null values or inheritance, so we work around that, e.g. using hacks like default values of -1 and empty strings i.e. "" to mimic null values. <i>And cut and paste between annotations like a crazed Heffalump. Very messy stuff.</i>

<i>Tigger wishes that Annotations were POJOs. Where specifying values is like setting bean properties. But they aren't. So we always convert or extract annotations into objects right away, and then conveniently forget about them. Then we can use nulls for properties not specified in the annotation, e.g. in the above <tt>GStringValidator</tt> example, <tt>minimumLength</tt> is null by default.</i>

<h3>Parsing and formatting</h3>
<i>"I thought Tiggers were smaller than that." "Not the big ones," said Tigger</i>

Our fields need to "format and parse." That is, they need to convert between objects and strings, and visa versa. <i>Because Pooh and friends read and write strings, but computers are objects and references which are ones and zeroes.</i>

<i>One bouncy way of doing this is having one Heffalump helper to format and parse them all.</i>

<pre>
public class ForestFriendsFormatter extends GDefaultFormatter {
   ...
   public String format(Object value, GProperty property) {
      if (property.isDateFormat()) return dateFormat.format(value);
      if (value instanceof FriendType) return value.toString();
      if (value instanceof ForestFood) return format((ForestFood) value);
      ...
      return super.format(value, property);
   }
   
   public Object parse(String string, GProperty property) throws GParseException {
      if (property.isDateFormat()) return dateFormat.parse(string);      
      if (property.isTimestampFormat()) return timestampFormat.parse(string);
      if (property.isString()) return string;
      if (property.isInteger()) return new Integer(string);
      ...
      return super.parse(string, property);
   }
   
   ... // custom formatting, e.g. format(ForestFood)
}
</pre>

Actually much of the above would be in the superclass i.e. <tt>GDefaultFormatter</tt>. We extend that to customise it, e.g. for our special types e.g. <tt>FriendType</tt> and <tt>ForestFood</tt>.

<i>As you can see, we don't buy into anything too fancy here in the forest. We have visiting to do, afternoon naps and things that keep us busy. So when we write software, which we do strictly mornings only, we hope that it works. If it doesn't, we fix it tomoro, time permitting. And anyway... what are cyclic dependencies, by the way?</i>

<h3>Custom fields</h3>
<i>"Tiggers can't climb downwards, because their tails get in the way, only upwards." Tigger</i>

We might implement custom fields, and overwrite <tt>format()</tt> and <tt>parse()</tt>, which are otherwise delegated by the <tt>GFieldComponent</tt>, firstly to its <tt>GFieldComponentHelper</tt> helper, then to its <tt>GProperty</tt> property descriptor, and finally to the <tt>GFormatter</tt> implementation. <i>Uh Hm. This is what Tigger calls 'whOOPy' programming, all this delegation and inheritance and friends-and-relations, is what makes it so nice and bouncy!</i>

<pre>
public FriendTypeField extends GComboBoxField<FriendType> {

   public FriendTypeField() {
      super();
      populate();      
   }

   public FriendTypeField(GFormHelper helper) {
      super(helper);
      populate();      
   }
   
   protected void populate() {
      for (FriendType friendType : FriendType.values()) {
         comboBoxModel.add(friendType.toString(), friendType);
      }
   }
   
   public String format(FriendType value) {
      return "A " + value.toString();
   }

   public FriendType parse(String string) {
      return super.parse(string.substring(2));
   }
}   
</pre>

A Small Problem is that our component factory creates regular text fields and what-not. So we can extend our factory i.e. <tt>GFormHelper</tt> to introduce a factory method like <tt>createFriendTypeField()</tt>, or we can use the <tt>GFormHelper.configure(comboBox)</tt> method, as follows.

<pre>
   FriendTypeField friendTypeField = new FriendTypeField();
   ...
   public void configure() {
      helper.configure(friendTypeField);
      ...
   }
</pre>

Or we can pass our <tt>GFormHelper</tt> context through to our custom combo box, so that its <tt>GComboBox</tt> superclass can invoke <tt>helper.configure(this)</tt> for us.

<i>So many choices and decisions... Time to have Owl over for tea and a little smackerel of something, shall we?</i>    

<h3>Form programming</h3>
<i>"Bounding up trees is easy for Tiggers. The difficulty is in the climbing down, backwards." Tigger</i>

Our form controller class might be implemented as follows.

<pre>
public FriendFormController implements ActionListener, GFieldListener {   
   FriendFormView friendFormView = new FriendFormView();   
   FriendFormBean friendFormBean = new FriendFormBean();   
   ...    
   public FriendFormController() {      
      friendFormView.helper.setController(this);
      clear();
      ...
   }

   protected void clear() {
      friendFormBean = new FriendFormBean();
      rebind();
   }

   protected void rebind() {
      friendFormView.helper.setModelBean(friendFormBean);
   }
   
   public void actionPerformed(ActionEvent event) {
      eventLogger.entering(event);
      // CURD events
      if (newAction.isSource(event)) {
         if (friendFormBean.isChanged()) {
            if (!guiHelper.showConfirmationDialog("You wanna loose changes?")) {
               return;
            }
         }
         clear();
      } else if (saveAction.isSource(event)) {
         if (!friendFormBean.isChanged()) {
            guiHelper.showMessageDialog("Nothing to save")) {
         } else if (friendFormBean.isDeleted()) {
            entityManager.friend.deleteEntity(friendFormBean.entityBean);
         } else if (friendFormBean.getValidationMessage() != null) {
            guiHelper.showMessageDialog(friendFormBean.getValidationMessage());
         } else {         
            entityManager.friend.saveEntity(friendFormBean.entityBean);
         }
      } else if (findAction.isSource(event)) {
         if (friendFormBean.getFriendName() == null) {
            guiHelper.showMessageDialog("Enter a name first");
         } else {
            FriendEntityBean friendEntity
               = entityManager.friend.getFriendByName(
                  friendFormBean.getFriendName());
            friendFormBean = new FriendFormBean(friendEntity);
            rebind();
         }         
      } else if (deleteAction.isSource(event)) {
         if (friendFormBean.isCreated()) clear();
         else friendFormBean.setDeleted(true);
      }      
   }
   
   public void fieldChanged(GFieldEvent event) {
      eventLogger.entering(event);
      if (friendFormView.friendName.isSource(event)) {
         traceLogger.finer(event.getFieldComponent(), 
               event.getOldValue(), event.getNewValue());
         if (event.isEntered() || event.isFocusLost()) {
            if (friendFormBean.getFriendName().trim().length() == 0) {
               guiHelper.showMessageDialog("Who dat?");
               return;
            }
         }
      }
      // TODO get more bouncy here
   }

   public void documentChanged(GFieldEvent event) {
   }   
}   
</pre>

To make it bouncy, we might introduce our own new event specifically for fields, for when the value of a field is changed by the user. When they tab out of the field (which is a "focus lost" <tt>FocusEvent</tt>), or press Enter (which causes an <tt>ActionEvent</tt>), we might invoke <tt>fieldChanged()</tt>. 

<img alt="" src="http://weblogs.java.net/blog/evanx/archive/tigger_sit_125.jpg" width="125" height="167" align=right hspace=16 />
We might throw a <tt>documentChanged()</tt> event handler into our <tt>GFieldListener</tt>, which comes into play when the user is editing a text field or what-not, courtesy of our <tt>GFormHelper</tt> listening for a <tt>DocumentEvent</tt> and turning that into a <tt>GFieldEvent</tt>.

<i>OK, let's wrap up. Time for a nap!</i>

<h3>Summary</h3>
<i>"When late morning rolls around and you're feeling a bit out of sorts, don't worry; you're probably just a little eleven o'clockish." Winnie the Pooh</i>

We continue from <i>Swing Turntables</i>, to apply "explicit properties" to the Swing <tt>JPanel</tt> and its fields.

We explicitly declare field components in our form, e.g. <tt>JTextField</tt>, <tt>JComboBox</tt> et al. Bean binding is performed implicitly, using the field names of the components. Annotations are used to specify layout, validation and stuff. Oh, and we introduce an interface for fields, to make them all look like honey pots. Our field components delegate to helpers and property descriptors to do all the work.

We program to a beautiful bouncy POJO "form model" rather than heavy Swing models. We reference our components as necessary, e.g. to invoke <tt>setEnabled()</tt>, <tt>requestFocusInWindow()</tt>, et al, and also to identify them as the source of events in our event handlers.

But we don't have to worry about extracting, converting and validating values from fields. We put that into a framework, where it belongs. A very simple framework mind you.

The framework handles events nicely and politely for us too. It does automatic event registration, event filtering (eg. ignoring events when they should be ignored), and introduces a handy custom event for fields, to hide the vagarities of <tt>ActionEvent</tt> and <tt>FocusEvent</tt>, which are mixed up with other types of components. Finally, it makes sure that exceptions thrown by event handlers are handled e.g. the user is told.

<i>And now for smackerel of something to eat, and then a lovely nap!</i>

<img alt="" src="http://weblogs.java.net/blog/evanx/archive/bees_and_sunflowers_175.jpg" width="175" height="131" align=left hspace=16 vspace=24 />

<h3>Sequels</h3>
<i>"Before beginning a Search, it is wise to ask someone what you are looking for before you begin looking for it." Winnie the Pooh</i>

The next article in this Swing series is <a href="http://weblogs.java.net/blog/evanx/archive/2006/06/swing_and_round_4.html">Inside Action</a> on Swing Actions (for buttons, toolbars, menus and hotkeys), and then <a href="http://weblogs.java.net/blog/evanx/archive/2006/07/swing_and_round_3.html">Framewarez</a> on building a tabbed application frame for our "worksheets."

<h3>Thanks</h3>

This blog was written using Netbeans, and previewed using Firefox (as hoofed in <a href="http://weblogs.java.net/blog/evanx/archive/2006/06/netbeans_my_web_1.html">Netbeans, my weblogging tool</a>. It was started in my sister's house, carried on in my brother's house, continued in my sister's office, and finished in my mom's cottage, on my new Windows XP notebook (as mooted in <a href="http://weblogs.java.net/blog/evanx/archive/2006/05/my_desktop_os_w.html">My Desktop OS: Windows XP</a> so... 
now you know! 

Pictures from http://yotophoto.com and flickr.com, notably http://flickr.com/people/agnieszka/

<h2>Resources</h2>

https://code.google.com/p/vellum/ - where i will collate these articles and their code.
